<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Register a snapshot repository | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'snapshots-register-repository.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/snapshots-register-repository.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/snapshots-register-repository.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/snapshots-register-repository.html" rel="nofollow" target="_blank">../en/snapshots-register-repository.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="snapshot-restore.html">Snapshot and restore</a></span>
»
<span class="breadcrumb-node">Register a snapshot repository</span>
</div>
<div class="navheader">
<span class="prev">
<a href="snapshot-restore.html">« Snapshot and restore</a>
</span>
<span class="next">
<a href="snapshots-take-snapshot.html">Take a snapshot of one or more indices »</a>
</span>
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="snapshots-register-repository"></a>Register a snapshot repository<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h2>
</div></div></div>

<p>You must register a snapshot repository before you can perform snapshot and
restore operations. We recommend creating a new snapshot repository for each
major version. The valid repository settings depend on the repository type.</p>
<p>If you register same snapshot repository with multiple clusters, only
one cluster should have write access to the repository. All other clusters
connected to that repository should set the repository to <code class="literal">readonly</code> mode.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>The snapshot format can change across major versions, so if you have
clusters on different versions trying to write the same repository, snapshots
written by one version may not be visible to the other and the repository could
be corrupted. While setting the repository to <code class="literal">readonly</code> on all but one of the
clusters should work with multiple clusters differing by one major version, it
is not a supported configuration.</p>
</div>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_backup
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1179.console"></div>
<p>To retrieve information about a registered repository, use a GET request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_snapshot/my_backup</pre>
</div>
<div class="console_widget" data-snippet="snippets/1180.console"></div>
<p>which returns:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "my_backup": {
    "type": "fs",
    "settings": {
      "location": "my_backup_location"
    }
  }
}</pre>
</div>
<p>To retrieve information about multiple repositories, specify a comma-delimited
list of repositories. You can also use the * wildcard when
specifying repository names. For example, the following request retrieves
information about all of the snapshot repositories that start with <code class="literal">repo</code> or
contain <code class="literal">backup</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_snapshot/repo*,*backup*</pre>
</div>
<div class="console_widget" data-snippet="snippets/1181.console"></div>
<p>To retrieve information about all registered snapshot repositories, omit the
repository name or specify <code class="literal">_all</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_snapshot</pre>
</div>
<div class="console_widget" data-snippet="snippets/1182.console"></div>
<p>or</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_snapshot/_all</pre>
</div>
<div class="console_widget" data-snippet="snippets/1183.console"></div>
<p>You can unregister a repository using the <a class="xref" href="delete-snapshot-repo-api.html" title="Delete snapshot repository API">delete
snapshot repository API</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">DELETE /_snapshot/my_backup</pre>
</div>
<div class="console_widget" data-snippet="snippets/1184.console"></div>
<p>When a repository is unregistered, Elasticsearch only removes the reference to the
location where the repository is storing the snapshots. The snapshots themselves
are left untouched and in place.</p>
<h3>
<a id="snapshots-filesystem-repository"></a>Shared file system repository<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h3>
<p>The shared file system repository (<code class="literal">"type": "fs"</code>) uses the shared file system to store snapshots. In order to register
the shared file system repository it is necessary to mount the same shared filesystem to the same location on all
master and data nodes. This location (or one of its parent directories) must be registered in the <code class="literal">path.repo</code>
setting on all master and data nodes.</p>
<p>Assuming that the shared filesystem is mounted to <code class="literal">/mount/backups/my_fs_backup_location</code>, the following setting should
be added to <code class="literal">elasticsearch.yml</code> file:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">path.repo: ["/mount/backups", "/mount/longterm_backups"]</pre>
</div>
<p>The <code class="literal">path.repo</code> setting supports Microsoft Windows UNC paths as long as at least server name and share are specified as
a prefix and back slashes are properly escaped:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">path.repo: ["\\\\MY_SERVER\\Snapshots"]</pre>
</div>
<p>After all nodes are restarted, the following command can be used to register the shared file system repository with
the name <code class="literal">my_fs_backup</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_fs_backup
{
    "type": "fs",
    "settings": {
        "location": "/mount/backups/my_fs_backup_location",
        "compress": true
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1185.console"></div>
<p>If the repository location is specified as a relative path this path will be resolved against the first path specified
in <code class="literal">path.repo</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_fs_backup
{
    "type": "fs",
    "settings": {
        "location": "my_fs_backup_location",
        "compress": true
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1186.console"></div>
<p>The following settings are supported:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">location</code>
</p>
</td>
<td valign="top">
<p>
Location of the snapshots. Mandatory.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">compress</code>
</p>
</td>
<td valign="top">
<p>
Turns on compression of the snapshot files. Compression is applied only to metadata files (index mapping and settings). Data files are not compressed. Defaults to <code class="literal">true</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">chunk_size</code>
</p>
</td>
<td valign="top">
<p>
Big files can be broken down into chunks during snapshotting if needed. Specify the chunk size as a value and
unit, for example: <code class="literal">1GB</code>, <code class="literal">10MB</code>, <code class="literal">5KB</code>, <code class="literal">500B</code>. Defaults to <code class="literal">null</code> (unlimited chunk size).
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_restore_bytes_per_sec</code>
</p>
</td>
<td valign="top">
<p>
Throttles per node restore rate. Defaults to <code class="literal">40mb</code> per second.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_snapshot_bytes_per_sec</code>
</p>
</td>
<td valign="top">
<p>
Throttles per node snapshot rate. Defaults to <code class="literal">40mb</code> per second.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">readonly</code>
</p>
</td>
<td valign="top">
<p>
Makes repository read-only.  Defaults to <code class="literal">false</code>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h3>
<a id="snapshots-read-only-repository"></a>Read-only URL repository<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h3>
<p>If you register the same snapshot repository with multiple clusters, only one
cluster should have write access to the repository. Having multiple clusters
write to the repository at the same time risks corrupting the contents of the
repository.</p>
<p>To reduce this risk, you can use URL repositories (<code class="literal">"type": "url"</code>) to give one
or more clusters read-only access to a shared file system repository. As URL
repositories are always read-only, they are a safer and more convenient
alternative to registering a read-only shared filesystem repository.</p>
<p>The URL specified in the <code class="literal">url</code> parameter should point to the root of the shared
filesystem repository.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_read_only_url_repository
{
  "type": "url",
  "settings": {
    "url": "file:/mount/backups/my_fs_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1187.console"></div>
<p>The <code class="literal">url</code> parameter supports the following protocols:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">file</code>
</li>
<li class="listitem">
<code class="literal">ftp</code>
</li>
<li class="listitem">
<code class="literal">http</code>
</li>
<li class="listitem">
<code class="literal">https</code>
</li>
<li class="listitem">
<code class="literal">jar</code>
</li>
</ul>
</div>
<p>URLs using the <code class="literal">file</code> protocol must point to the location of a shared filesystem
accessible to all master and data nodes in the cluster. This location must be
registered in the <code class="literal">path.repo</code> setting, similar to a
<a class="xref" href="snapshots-register-repository.html#snapshots-filesystem-repository" title="Shared file system repository">shared file system repository</a>.</p>
<p>URLs using the <code class="literal">ftp</code>, <code class="literal">http</code>, or <code class="literal">https</code> protocols must be explicitly allowed with the
<code class="literal">repositories.url.allowed_urls</code> setting. This setting supports wildcards (<code class="literal">*</code>)
in place of a host, path, query, or fragment in the URL. For example:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">repositories.url.allowed_urls: ["http://www.example.org/root/*", "https://*.mydomain.com/*?*#*"]</pre>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>URLs using the <code class="literal">ftp</code>, <code class="literal">http</code>, <code class="literal">https</code>, or <code class="literal">jar</code> protocols do not need to
be registered in the <code class="literal">path.repo</code> setting.</p>
</div>
</div>
<h3 class="xpack">
<a id="snapshots-source-only-repository"></a>Source only repository<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h3>
<p>A source repository enables you to create minimal, source-only snapshots that take up to 50% less space on disk.
Source only snapshots contain stored fields and index metadata. They do not include index or doc values structures
and are not searchable when restored. After restoring a source-only snapshot, you must <a class="xref" href="docs-reindex.html" title="Reindex API">reindex</a>
the data into a new index.</p>
<p>Source repositories delegate to another snapshot repository for storage.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Source only snapshots are only supported if the <code class="literal">_source</code> field is enabled and no source-filtering is applied.
When you restore a source only snapshot:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The restored index is read-only and can only serve <code class="literal">match_all</code> search or scroll requests to enable reindexing.
</li>
<li class="listitem">
Queries other than <code class="literal">match_all</code> and <code class="literal">_get</code> requests are not supported.
</li>
<li class="listitem">
The mapping of the restored index is empty, but the original mapping is available from the types top
level <code class="literal">meta</code> element.
</li>
</ul>
</div>
</div>
</div>
<p>When you create a source repository, you must specify the type and name of the delegate repository
where the snapshots will be stored:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _snapshot/my_src_only_repository
{
  "type": "source",
  "settings": {
    "delegate_type": "fs",
    "location": "my_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1188.console"></div>
<h3>
<a id="snapshots-repository-plugins"></a>Repository plugins<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h3>
<p>Other repository backends are available in these official plugins:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-s3.html" class="ulink" target="_top">repository-s3</a> for S3 repository support
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-hdfs.html" class="ulink" target="_top">repository-hdfs</a> for HDFS repository support in Hadoop environments
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-azure.html" class="ulink" target="_top">repository-azure</a> for Azure storage repositories
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-gcs.html" class="ulink" target="_top">repository-gcs</a> for Google Cloud Storage repositories
</li>
</ul>
</div>
<h3>
<a id="snapshots-repository-verification"></a>Repository verification<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h3>
<p>When a repository is registered, it’s immediately verified on all master and data nodes to make sure that it is functional
on all nodes currently present in the cluster. The <code class="literal">verify</code> parameter can be used to explicitly disable the repository
verification when registering or updating a repository:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_unverified_backup?verify=false
{
  "type": "fs",
  "settings": {
    "location": "my_unverified_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1189.console"></div>
<p>The verification process can also be executed manually by running the following command:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_snapshot/my_unverified_backup/_verify</pre>
</div>
<div class="console_widget" data-snippet="snippets/1190.console"></div>
<p>It returns a list of nodes where repository was successfully verified or an error message if verification process failed.</p>
<h3>
<a id="snapshots-repository-cleanup"></a>Repository cleanup<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/register-repository.asciidoc">edit</a>
</h3>
<p>Repositories can over time accumulate data that is not referenced by any existing snapshot. This is a result of the data safety guarantees
the snapshot functionality provides in failure scenarios during snapshot creation and the decentralized nature of the snapshot creation
process. This unreferenced data does in no way negatively impact the performance or safety of a snapshot repository but leads to higher
than necessary storage use. In order to clean up this unreferenced data, users can call the cleanup endpoint for a repository which will
trigger a complete accounting of the repositories contents and subsequent deletion of all unreferenced data that was found.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_snapshot/my_repository/_cleanup</pre>
</div>
<div class="console_widget" data-snippet="snippets/1191.console"></div>
<p>The response to a cleanup request looks as follows:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "results": {
    "deleted_bytes": 20,
    "deleted_blobs": 5
  }
}</pre>
</div>
<p>Depending on the concrete repository implementation the numbers shown for bytes free as well as the number of blobs removed will either
be an approximation or an exact result. Any non-zero value for the number of blobs removed implies that unreferenced blobs were found and
subsequently cleaned up.</p>
<p>Please note that most of the cleanup operations executed by this endpoint are automatically executed when deleting any snapshot from a
repository. If you regularly delete snapshots, you will in most cases not get any or only minor space savings from using this functionality
and should lower your frequency of invoking it accordingly.</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="snapshot-restore.html">« Snapshot and restore</a>
</span>
<span class="next">
<a href="snapshots-take-snapshot.html">Take a snapshot of one or more indices »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>